home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / cpp_libs / cool / ge_cool.lha / GE_COOL2.1 / man / oldman3 / Stack.3T~ < prev    next >
Text File  |  1992-06-26  |  8KB  |  265 lines
  1. .TH STACK
  2. .SH NAME
  3. Stack<Type>\f1  A dynamic, parameterized stack
  4. .SH SYNOPSIS
  5. #include <cool/Stack.h>
  6. .SH DESCRIPTION
  7. The \f3Stack<Type>\f1 class implements a conventional first-in, last-out datastructure that holds a user-specified data type. All memory management and 
  8. initialization is encapsulated and performed by the class constructors and 
  9. member functions. Stack objects can be either static-sized or dynamic. Stacks 
  10. are, by default, dynamic in nature. A static-sized stack object is selected by 
  11. setting the growth allocation size to zero or by passing in a pointer to a 
  12. block of user-supplied storage to the constructor. If a stack is of static size 
  13. and an operation is performed that requires more storage, an 
  14.  \f3\f3Error\f1\f1 
  15. exception is raised.
  16. .SH Base Classes
  17.  Stack, 
  18. .SH Friend Classes
  19. None
  20. .SH Constructors
  21. .TP
  22. \f3Stack<Type> ();\f1
  23. Creates an empty stack of the specified type.
  24. .TP
  25. \f3Stack<Type> \f3(unisgned long \f2number\f3);\f1
  26. Allocates enough storage for a stack of a specific type to hold 
  27.  number 
  28. of elements.
  29. .TP
  30. \f3Stack<Type> (const Stack<Type>& stk\f3);\f1
  31. Duplicates the size and value of a stack object 
  32.  stk .
  33. .TP
  34. \f3Stack<Type> (void* \f2storage\f3, unsigned long \f2number\f3);\f1
  35. Creates a static-sized stack object for 
  36.  number 
  37. of elements whose storage 
  38.  storage 
  39. is provided by the user. If an object of this type attempts to grow 
  40. dynamically or the programmer invokes the 
  41.  resize 
  42. member function, an 
  43.  \f3\f3Error\f1\f1 
  44. exception is raised.
  45. .SH Member Functions
  46. .TP
  47.  inline long capacity () const;
  48. Returns the maximum number of elements the stack can contain.
  49. .TP
  50.  inline void clear ();
  51. Sets the number of elements in the stack to zero.
  52. .TP
  53. \f3Boolean find (const Type& value\f3);\f1
  54. Searches the stack for 
  55.  value . 
  56. If 
  57.  value 
  58. is found, this function returns 
  59.  
  60.  TRUE ; 
  61. otherwise, this function returns 
  62.  
  63.  FALSE .
  64. .TP
  65.  inline Boolean is_empty () const;
  66. Returns 
  67.  
  68.  TRUE 
  69. if the stack has no elements; otherwise, this function returns 
  70.  
  71.  FALSE .
  72. .TP
  73.  inline long length () const;
  74. Returns the number of elements in the stack.
  75. .TP
  76. \f3Stack<Type>& \f3operator= (const Stack<Type>& stk\f3);\f1
  77. Overloads the assignment operator for the \f3Stack<Type>\f1
  78. class and assigns
  79.  stk 
  80. to 
  81. the stack object by duplicating the size and element values. If the stack 
  82. object is prohibited from dynamically growing, an 
  83.  \f3\f3Error\f1\f1 
  84. exception is raised.
  85. .TP
  86. \f3Boolean operator== (const Stack<Type>& stk\f3) const;\f1
  87. Overloads the equality operator for the \f3Stack<Type>\f1 class. Returns 
  88.  
  89.  TRUE 
  90. if the 
  91. stacks have an equal number of elements with the same values; otherwise this 
  92. function returns 
  93.  
  94.  FALSE .
  95. .TP
  96. \f3inline Boolean operator!= (const Stack<Type>& stk\f3) const;\f1
  97. Overloads the inequality operator for the \f3Stack<Type>\f1 class. This function 
  98. returns 
  99.  
  100.  TRUE 
  101. if the stacks have a unequal number of elements or unequal values; 
  102. otherwise this function returns 
  103.  
  104.  FALSE .
  105. .TP
  106. \f3inline Type& operator[\^] (unsigned long \f2number\f3);\f1
  107. Overloads the index operator for the \f3Stack<Type>\f1 class. This function returns a 
  108. reference to the element of the stack that is 
  109.  number 
  110. of elements from the top 
  111. of the stack. If 
  112.  number 
  113. is greater than the size of the stack, an 
  114.  \f3\f3Error\f1\f1 
  115. exception is raised.
  116. .TP
  117.  inline Type& pop ();
  118. Removes and returns a reference to the top element on the stack. If the number 
  119. of elements (that is, length) has been set to a zero-relative index greater 
  120. than the size of the stack, an 
  121.  \f3\f3Error\f1\f1 
  122. exception is raised.
  123. .TP
  124. \f3Type& popn (long \f2n\f3);\f1
  125. Pops 
  126.  n 
  127. elements off the stack, returning a reference to the last one popped off 
  128. the stack. With an argument of zero, this function returns the top item of the 
  129. stack without removing it. If the number of elements to pop is negative, an 
  130.  \f3\f3Error\f1\f1 
  131. exception is raised.
  132. .TP
  133. \f3long position (const Type& value\f3) const;\f1
  134. Searches the stack for 
  135.  value . 
  136. If 
  137.  value 
  138. is found, this function returns the 
  139. zero-relative index, from the top of the stack, of that element; otherwise, 
  140. this function returns \-1.
  141. .TP
  142. \f3inline Boolean push (const Type& value\f3);\f1
  143. Pushes 
  144.  value 
  145. onto the top of a stack. If required and not prohibited, this 
  146. function grows the stack object. This function returns 
  147.  
  148.  TRUE 
  149. if successful; 
  150. otherwise, this function returns 
  151.  
  152.  FALSE . 
  153. If the stack is prohibited from growing 
  154. dynamically, an 
  155.  \f3\f3Error\f1\f1 
  156. exception is raised.
  157. .TP
  158. \f3Boolean pushn (const Type& value\f3, long \f2n\f3);\f1
  159. Pushes 
  160.  n 
  161. items onto the top of the stack, all of which have the specified 
  162.  value . 
  163. When 
  164.  n 
  165. is zero, this function replaces the top item on the stack with
  166.  value . 
  167. If required and not prohibited, this function grows the stack object. 
  168. This function returns 
  169.  
  170.  TRUE 
  171. if successful; otherwise, this function returns
  172.  
  173.  FALSE . 
  174. If the stack is prohibited from growing dynamically, an 
  175.  \f3\f3Error\f1\f1 
  176. exception is raised.
  177. .TP
  178. \f3void resize (long \f2number\f3);\f1
  179. Resizes the stack for at least 
  180.  number 
  181. of elements. If a growth ratio has been 
  182. selected and it satisfies the resize request, the stack is grown by this ratio. 
  183. If the stack is prohibited from dynamically growing, an 
  184.  \f3\f3Error\f1\f1 
  185. exception is raised.
  186. .TP
  187. \f3inline void set_alloc_size (int \f2size\f3);\f1
  188. Updates the allocation growth size to be used when the growth ratio is zero. 
  189. Default allocation growth size is 100 bytes. Setting the allocation growth size 
  190. to zero results in a static-sized object. If 
  191.  size 
  192. is zero or negative, an 
  193.  \f3\f3Error\f1\f1 
  194. exception is raised.
  195. .TP
  196. \f3inline void set_compare (\f2Stack_Compare\f3 = NULL);\f1
  197. Sets the compare function for this class of stack. 
  198.  Stack_Compare 
  199. is a 
  200. user-defined function of type 
  201.  Boolean 
  202. (\f2*Function\f1)(\f3const Type&\f1, \f3const Type&\f1). If 
  203. no such function is provided, the 
  204.  operator== 
  205. for the type over which the class 
  206. is parameterized is used.
  207. .TP
  208. \f3inline void set_growth_ratio (float \f2ratio\f3);\f1
  209. Updates the growth ratio for this instance of a stack to 
  210.  ratio . 
  211. When a stack 
  212. needs to grow, the current size is multiplied by the ratio to determine the new 
  213. size. If 
  214.  ratio 
  215. is negative, an 
  216.  \f3\f3Error\f1\f1 
  217. exception is raised.
  218.  
  219. .TP
  220. \f3inline long set_length (long \f2number\f3);\f1
  221. Specifies the number of elements in a stack to allow random access via the 
  222. overloaded 
  223.  operator[\^] 
  224. member function. If 
  225.  number 
  226. is larger than the storage 
  227. allocated, this function truncates 
  228.  number 
  229. to the largest value that the 
  230. allocated size will support. This function returns the new element count. If
  231.  number 
  232. is negative, an 
  233.  \f3\f3Error\f1\f1 
  234. exception is raised.
  235. .TP
  236.  inline Type& top ();
  237. Returns (without removing) a reference to the top element of the stack. If the 
  238. number of elements (that is, length) has been set to a zero-relative index 
  239. greater than the size of the stack, an 
  240.  \f3\f3Error\f1\f1 
  241. exception is raised.
  242. .SH Friend Functions
  243. .TP
  244. \f3friend ostream& operator<< (ostream& \f2os\f3, const Stack<Type>& stk\f3);\f1
  245. Overloads the output operator for a reference to a \f3Stack<Type>\f1 object to 
  246. provide a \p
  247. formatted output capability.
  248. .TP
  249. \f3inline friend ostream& operator<< (ostream& \f2os\f3, const Stack<Type>* stk\f3);\f1
  250. Overloads the output operator for a pointer to a \f3Stack<Type>\f1 object to provide 
  251. a \p
  252. formatted output capability.
  253. .SH COPYRIGHT
  254.  
  255. Copyright (C) 1991 Texas Instruments Incorporated.
  256.  
  257. Permission is granted to any individual or institution to use, copy, modify,
  258. and distribute this software, provided that this complete copyright and
  259. permission notice is maintained, intact, in all copies and supporting
  260. documentation.
  261.  
  262. Texas Instruments Incorporated provides this software "as is" without
  263. express or implied warranty.
  264.  
  265.